ASCII text
Formatting messages
Formatting in 30 seconds
To format messages you use special syntax.
*italic*or_italic_becomes italic.**bold**or__bold__becomes bold.~~strikethrough~~becomesstrikethrough.++inserted++becomes inserted.--deleted--becomesdeleted.[link](https://wikipedia.org)becomes link.becomes
.
`code`becomescode.Paragraphs are separated by a blank line.
~~~or~~~languagestarts a code block;~~~ends it.#starts a heading. The number of#s determines the level.>starts a blockquote.*or<number>.starts a list item.;makes a comment.A backslash at the end of a line forces a line break.
Introduction
The roundabout uses a markdown-like syntax to format messages, including commit messages, comments, descriptions, files and so on.
It is designed to be similar in philosophy to markdown, and for markdown users it should be really similar (this is why we use Markdown's extension and mime types provisionally, until there is more adoption).
Currently not all markdown (as described in Gruber's initial release) features are supported, but the most common use cases should be covered. Conversely, some extra features are available, primarily ones useful in a code review environment. Some special cases are handled differently compared to Gruber's markdown.
Very importantly, it is not CommonMark compliant, like you see in this sentence which had an underlined word.
There is also not a formalised specification for the syntax; first we need to stabilise it.
The syntax does not specify a particular output format, but the reference implementation shipped here outputs HTML.
Philosophy
Like the original markdown, the goal with this syntax is to make it possible to writeplain text that has formatting as a bonus when it's supported.
A document should be readable and publishable even if a rendered version is not available, in its raw form, without looking like it's been marked up with tags or formatting instructions.
Easy to read: The syntax should be understandable enough so that it is readable without rendering it, even for someone not familiar with this syntax.
Easy to write: The syntax should be easy to write using a regular keyboard, only in plain text. The renderer will try its best to understand the human.
However, it should be still easy to read. The syntax should look like what it represents, even if it's a little harder to write it.
Predictable: Edge-cases should be avoided as much as possible, as long as it still understands the writer's intent.
Easy (and fast) to render: A reasonably fast renderer should be possible to write with a reasonable amount of effort and a few lines of code in a high-level language.
Unambiguous: There should not be confusion in parsing. Precedence should be clear, and it should always prioritise the most likely interpretation.
Extensible: Without breaking forward compatibility, it should be possible to add new features to the syntax programmatically, including special interest features like charts, sheet music, or code review features.
Semantic: Available features should never imply altering the document's presentation, but rather its structure and meaning. Clients could style all features as they wish, as long as they reasonably make sense. Allowing the user to add stylesheets is fine, as long as the document itself doesn't contain any style information, and they're not mandatory.
Secure: The syntax should not allow for arbitrary code execution, or any other security risk. It should be safe to render untrusted documents.
Familiar and traditional: Users should be able to learn it in a few minutes, it should be similar to markdown, and follow traditions rooted in plain text mediums, such as email, Usenet, IRC or typewriters.
Structure and terminology
A document is a sequence ofblocks_. Many blocks, but not all, can contain other _child blocks too. Most blocks can hold content, in which case they can also hold _inline elements_.
Most inline elements can hold other inlines as well, but they can't hold blocks.
Some elements, both blocks and inlines, can have _attributes_. Generally this is specified in a clear way in the syntax.
Any sequence of characters is a valid document.
Blocks
Void
A void is just a blank line (appears white, i.e. is empty or only has spaces). It is used to force block separation and is not output in the rendered document.
block 1 block 2
turns into
block 1
block 2
Comment
If a line starts with ;, it is turned into a void, to allow the writer to
add comments to the document. This is not output in the rendered document,
like any other void. It also separates blocks.
block 1 ; this is a comment block 2
turns into
block 1
block 2
Plain text mediums haven't got a tradition of leaving comments. But the
character ; was used as it is very unlikely to appear at the start of a
line.
The space is not required. The line just has to begin with a semicolon.
Paragraph
Anything not recognised as another block is considered a paragraph. You can use voids to separate paragraphs. Within a paragraph, whitespace is collapsed like in HTML, so any sequence of spaces will become one space, and newlines will be ignored, although the rendered output can automatically wrap lines.
To force a line break in a paragraph, end the line with a backslash.
Important:\ Unlike in standard markdown, two trailing spaces do not force a line break. That syntax is often considered confusing: in most editors, trailing spaces are invisible.
Instead, use a backslash at the end of the line.
This is a paragraph. This is a new line in the same paragraph. It doesn't wrap, unless you force it to.\ Now it wraps. This is a new paragraph.
turns into
This is a paragraph. This is a new line in the same paragraph. It doesn't wrap, unless you force it to.\ Now it wraps.
This is a new paragraph.
Paragraphs can't contain other blocks because it wouldn't make sense, but they can contain inline elements.
When a block that can contain other blocks has plain text, it is automatically a paragraph, since the parsing is recursive.
Heading
ATX-style heading
ATX-style headings are lines which start with one or more #, then a space.
The number of #s determines the heading level.
For H1 you would use
#.For H2 you would use
##.For H3 you would use
###.For H4 you would use
####.For H5 you would use
#####.For H6 you would use
######.
# Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6
turns into
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Important:\ Unlike in standard markdown, a space after the
#is required. This is because it is more readable and less likely to convert unintended sequences of#s into headings. Additionally, markdown had a rarely-used feature that allowed closing headers with#s, which is not supported here.
Setext-style heading
Setext headings are only available for H1 and H2. To create an H1,
underline it with =, and to create an H2, underline it with -.
Heading 1 ========= Heading 2 ---------
turns into
Heading 1
Heading 2
The number of underlines doesn't matter; you can even use just one. However, it looks nicer if you match the width of the heading. I personally prefer this style where available as it gives more visual weight to the heading and matches traditions.
All headings are single-line. Headings cannot contain other blocks, but they can contain inline elements.
Fence (code block)
A fence is a block that starts and ends with either ```
or ~~~. Generally it is used for program code.
After the opening fence, on the same line, there can be a language descriptor. Usually it is used to apply syntax highlighting to the code inside, but it could be used for other purposes.
turns into ```text This is a code block.
The language descriptor is optional. If it is not present, the renderer should not apply syntax highlighting, and the block is assumed to be plain text.
Obviously, since the fence contains text that should be rendered specially, it can't contain any other blocks or inlines.
Indented code blocks are currently not supported, but they might be in the future.
Blockquote
A blockquote is a block that starts with >. It is used to quote
other text, or to set aside text that is not part of the main
content.
A space after the > is not required, but recommended for
readability.
Blockquotes can contain other blocks, but not inlines. If you want inlines they will be in a paragraph anyways.
> This is a blockquote. > It can contain multiple lines. > ## And even other blocks. > > And they can be nested. > > If this isn't what you want, it can have voids too.
turns into
This is a blockquote. It can contain multiple lines.
And even other blocks.
And they can be nested.
If this isn't what you want, it can have voids too.
List
A list is a sequence of list items. List items are represented by lines
that start with *, +, or -, followed by a space, or with a number
followed by a period. The first type creates a bullet (unordered) list,
and the second type creates a numbered (ordered) list. For ordered lists,
the number doesn't matter; it always begins from 1 in HTML.
List items can contain other blocks.
A list item can have continuation lines and contain multiple blocks. Continuation lines are indented with _two spaces_.
Important:\ Unlike in standard markdown, a space after the
*,+or-is required. Also unlike in standard markdown, parsing works normally inside list items, but they must be indented with two spaces, not four. This is because it looks nicer with unordered lists:* This is a list item. This is a continuation line. ; this version vs. * This is a list item. This is a continuation line. ; real markdown
Horizontal rule
A horizontal rule is a line that contains only hyphens, underscores, or asterisks, and optionally spaces. The length must be at least 3.
---------------
________
* * *
turns into
Summary of blocks
Void: blank line, or line starting with
;, empty and not output.Paragraph: anything not recognised as another block, can contain
Heading: prefix with
#or underline, single-line, can containFence: code block, starts and ends with
~~~or```,Blockquote: starts with
>, can contain other blocks with recursiveList: starts with
*,+,-, or<number>., continuation linesHorizontal rule: line with at least 3 characters, hyphens,
Inline elements
Text
Technically not an inline element, represented by a simple text in the output. Anything not otherwise recognised is text.
Emphasis
Emphasis is represented by * or _ surrounding the text. When using _,
the emphasis must be surrounded by spaces or start/end of the line.
There can be at most 7 markers on each side, the number of opening markers must be exactly the same as the number of closing markers, and they cannot be mixed, unlike in standard markdown. (Maybe this will change in the future, but we'll see.) However mixing them sometimes works, only when nesting makes sense.
The number of markers is interpreted as a sum of powers of 2. If it's 4 or more then there's the third level of emphasis, if the remainder is 2 or more then there's the second level of emphasis, and if there's a remainder then there's the first level of emphasis. You can see how they look below:
level 1
level 2
level 1+2
level 3
level 1+3
level 2+3
level 1+2+3
The roundabout styles level 1 as italic, level 2 as bold, and level 3 as underlined.
Strikethrough
Strikethrough is represented by ~~ surrounding the text.
Diff marker
Diff markers are represented by ++ on either side of the text for inserted
text and -- for deleted text.
Link
Links are represented by [text](url). The text can contain inline elements.
Title attributes are currently not supported, but they will be.
Autolink
Autolinks are represented by <url>. With an autolink, the URL is the link
text as well.
Image
Images are represented by .
Code
Code is represented by ` surrounding the text.
Using two backticks is not currently supported.
Summary of inline elements
Text: anything not recognised as another inline element.
Emphasis:
*or_surrounding the text, at most 7 markers on each side.Strikethrough:
~~surrounding the text.Diff marker:
++or--surrounding the text.Link:
[text](url), text can contain inline elements.Image:
.Code:
`surrounding the text.
1
Formatting messages
2
===================
3
Formatting in 30 seconds
5
------------------------
6
To format messages you use special syntax.
8
* `*italic*` or `_italic_` becomes *italic*.
10
* `**bold**` or `__bold__` becomes **bold**.
11
* `~~strikethrough~~` becomes ~~strikethrough~~.
12
* `++inserted++` becomes ++inserted++.
13
* `--deleted--` becomes --deleted--.
14
* `[link](https://wikipedia.org)` becomes [link](https://wikipedia.org).
15
* ``
16
becomes .
17
* ``code`` becomes `code`.
18
* Paragraphs are separated by a blank line.
19
* `~~~` or `~~~language` starts a code block; `~~~` ends it.
20
* `#` starts a heading. The number of `#`s determines the level.
21
* `>` starts a blockquote.
22
* `*` or `<number>. ` starts a list item.
23
* `;` makes a comment.
24
* A backslash at the end of a line forces a line break.
25
Introduction
27
------------
28
The roundabout uses a markdown-like syntax to format messages, including
30
commit messages, comments, descriptions, files and so on.
31
It is designed to be similar in philosophy to markdown, and for markdown
33
users it should be really similar (this is why we use Markdown's extension
34
and mime types provisionally, until there is more adoption).
35
Currently not all markdown (as described in Gruber's initial release)
37
features are supported, but the most common use cases should be covered.
38
Conversely, some extra features are available, primarily ones useful in
39
a code review environment. Some special cases are handled differently
40
compared to Gruber's markdown.
41
Very importantly, it is *******not******* CommonMark compliant, like you see
43
in this sentence which had an underlined word.
44
There is also not a formalised specification for the syntax; first we need
46
to stabilise it.
47
The syntax does not specify a particular output format, but the reference
49
implementation shipped here outputs HTML.
50
Philosophy
52
----------
53
Like the original markdown, the goal with this syntax is to make it possible
55
to write _plain_ text that has formatting as a bonus when it's supported.
56
A document should be readable and publishable even if a rendered version is
58
not available, in its raw form, without looking like it's been marked up
59
with tags or formatting instructions.
60
* **Easy to read:** The syntax should be understandable enough
62
so that it is readable without rendering it, even for someone not familiar
63
with this syntax.
64
* **Easy to write:** The syntax should be easy to write using a
65
regular keyboard, only in plain text. The renderer will try its best to
66
understand the human.
67
* However, it should be still easy to read. The syntax should look like
68
what it represents, even if it's a little harder to write it.
69
* **Predictable:** Edge-cases should be avoided as much as
70
possible, as long as it still understands the writer's intent.
71
* **Easy (and fast) to render:** A reasonably fast renderer should
72
be possible to write with a reasonable amount of effort and a few lines of
73
code in a high-level language.
74
* **Unambiguous:** There should not be confusion in parsing.
75
Precedence should be clear, and it should always prioritise the most likely
76
interpretation.
77
* **Extensible:** Without breaking forward compatibility, it should
78
be possible to add new features to the syntax programmatically, including
79
special interest features like charts, sheet music, or code review features.
80
* **Semantic:** Available features should never imply altering
81
the document's presentation, but rather its structure and meaning. Clients
82
could style all features as they wish, as long as they reasonably make sense.
83
Allowing the user to add stylesheets is fine, as long as the document itself
84
doesn't contain any style information, and they're not mandatory.
85
* **Secure:** The syntax should not allow for arbitrary code execution, or any
86
other security risk. It should be safe to render untrusted documents.
87
* **Familiar and traditional**: Users should be able to learn it in a few minutes,
88
it should be similar to markdown, and follow traditions rooted in plain text
89
mediums, such as email, Usenet, IRC or typewriters.
90
Structure and terminology
92
-------------------------
93
A document is a sequence of _blocks_. Many blocks, but not all, can contain other
95
_child_ blocks too. Most blocks can hold content, in which case they can also hold
96
_inline elements_.
97
Most inline elements can hold other inlines as well, but they can't hold blocks.
99
Some elements, both blocks and inlines, can have _attributes_. Generally this is
101
specified in a clear way in the syntax.
102
Any sequence of characters is a valid document.
104
Blocks
106
------
107
### Void
109
A void is just a blank line (appears white, i.e. is empty or only has spaces).
110
It is used to force block separation and is not output in the rendered document.
111
~~~
113
block 1
114
block 2
116
~~~
117
turns into
119
block 1
121
block 2
123
#### Comment
125
If a line starts with `;`, it is turned into a void, to allow the writer to
126
add comments to the document. This is not output in the rendered document,
127
like any other void. It also separates blocks.
128
~~~
130
block 1
131
; this is a comment
132
block 2
133
~~~
134
turns into
136
block 1
138
; this is a comment
139
block 2
140
Plain text mediums haven't got a tradition of leaving comments. But the
142
character `;` was used as it is very unlikely to appear at the start of a
143
line.
144
The space is not required. The line just has to begin with a semicolon.
146
### Paragraph
148
Anything not recognised as another block is considered a paragraph. You can
149
use voids to separate paragraphs. Within a paragraph, whitespace is collapsed
150
like in HTML, so any sequence of spaces will become one space, and newlines
151
will be ignored, although the rendered output can automatically wrap lines.
152
To force a line break in a paragraph, end the line with a backslash.
154
> **Important:**\
156
> Unlike in standard markdown, two trailing spaces do not force a line break.
157
> That syntax is often considered confusing: in most editors, trailing spaces
158
> are invisible.
159
>
160
> Instead, use a backslash at the end of the line.
161
~~~
163
This is a paragraph.
164
This is a new line in the same paragraph.
165
It doesn't wrap, unless you force it to.\
166
Now it wraps.
167
This is a new paragraph.
169
~~~
170
turns into
172
This is a paragraph.
174
This is a new line in the same paragraph.
175
It doesn't wrap, unless you force it to.\
176
Now it wraps.
177
This is a new paragraph.
179
Paragraphs can't contain other blocks because it wouldn't make sense, but
181
they can contain inline elements.
182
When a block that can contain other blocks has plain text, it is
184
automatically a paragraph, since the parsing is recursive.
185
### Heading
187
#### ATX-style heading
188
ATX-style headings are lines which start with one or more `#`, then a space.
189
The number of `#`s determines the heading level.
190
* For H1 you would use `#`.
192
* For H2 you would use `##`.
193
* For H3 you would use `###`.
194
* For H4 you would use `####`.
195
* For H5 you would use `#####`.
196
* For H6 you would use `######`.
197
~~~
199
# Heading 1
200
## Heading 2
201
### Heading 3
202
#### Heading 4
203
##### Heading 5
204
###### Heading 6
205
~~~
206
turns into
208
# Heading 1
210
## Heading 2
211
### Heading 3
212
#### Heading 4
213
##### Heading 5
214
###### Heading 6
215
> **Important:**\
217
> Unlike in standard markdown, a space after the `#` is required.
218
> This is because it is more readable and less likely to convert
219
> unintended sequences of `#`s into headings.
220
> Additionally, markdown had a rarely-used feature that allowed
221
> closing headers with `#`s, which is not supported here.
222
#### Setext-style heading
224
Setext headings are only available for H1 and H2. To create an H1,
225
underline it with `=`, and to create an H2, underline it with `-`.
226
~~~
228
Heading 1
229
=========
230
Heading 2
232
---------
233
~~~
234
turns into
236
Heading 1
238
=========
239
Heading 2
241
---------
242
The number of underlines doesn't matter; you can even use just one.
244
However, it looks nicer if you match the width of the heading.
245
I personally prefer this style where available as it gives more visual
246
weight to the heading and matches traditions.
247
All headings are single-line. Headings cannot contain other blocks,
249
but they can contain inline elements.
250
### Fence (code block)
252
A fence is a block that starts and ends with either `````
253
or `~~~`. Generally it is used for program code.
254
After the opening fence, on the same line, there can be a language
256
descriptor. Usually it is used to apply syntax highlighting to the
257
code inside, but it could be used for other purposes.
258
~~~
260
```text
261
This is a code block.
262
```
263
~~~
264
turns into
266
```text
268
This is a code block.
269
```
270
The language descriptor is optional. If it is not present, the
272
renderer should not apply syntax highlighting, and the block is
273
assumed to be plain text.
274
Obviously, since the fence contains text that should be rendered
276
specially, it can't contain any other blocks or inlines.
277
Indented code blocks are currently not supported, but they might
279
be in the future.
280
### Blockquote
282
A blockquote is a block that starts with `>`. It is used to quote
283
other text, or to set aside text that is not part of the main
284
content.
285
A space after the `>` is not required, but recommended for
287
readability.
288
Blockquotes can contain other blocks, but not inlines. If you want
290
inlines they will be in a paragraph anyways.
291
~~~
293
> This is a blockquote.
294
> It can contain multiple lines.
295
> ## And even other blocks.
296
> > And they can be nested.
297
>
298
> If this isn't what you want, it can have voids too.
299
~~~
300
turns into
302
> This is a blockquote.
304
> It can contain multiple lines.
305
> ## And even other blocks.
306
> > And they can be nested.
307
>
308
> If this isn't what you want, it can have voids too.
309
### List
311
A list is a sequence of list items. List items are represented by lines
312
that start with `*`, `+`, or `-`, followed by a space, or with a number
313
followed by a period. The first type creates a bullet (unordered) list,
314
and the second type creates a numbered (ordered) list. For ordered lists,
315
the number doesn't matter; it always begins from 1 in HTML.
316
List items can contain other blocks.
318
A list item can have continuation lines and contain multiple blocks.
320
Continuation lines are indented with _two spaces_.
321
> **Important:**\
323
> Unlike in standard markdown, a space after the `*`, `+` or `-` is
324
> required.
325
> Also unlike in standard markdown, parsing works normally inside
326
> list items, but they must be indented with two spaces, not four.
327
> This is because it looks nicer with unordered lists:
328
> ~~~
329
> * This is a list item.
330
> This is a continuation line.
331
> ; this version vs.
332
> * This is a list item.
333
> This is a continuation line.
334
> ; real markdown
335
> ~~~
336
### Horizontal rule
338
A horizontal rule is a line that contains only hyphens, underscores,
339
or asterisks, and optionally spaces. The length must be at least 3.
340
~~~
342
---------------
343
________
345
* * *
347
~~~
348
turns into
350
---------------
352
________
354
* * *
356
### Summary of blocks
358
1. **Void:** blank line, or line starting with `;`, empty and not output.
359
2. **Paragraph:** anything not recognised as another block, can contain
360
inline elements but not blocks.
361
3. **Heading:** prefix with `#` or underline, single-line, can contain
362
inline elements.
363
4. **Fence:** code block, starts and ends with `~~~` or `````,
364
can contain only text, optionally with a language descriptor.
365
5. **Blockquote:** starts with `>`, can contain other blocks with recursive
366
parsing.
367
6. **List:** starts with `*`, `+`, `-`, or `<number>.`, continuation lines
368
are indented with two spaces, can contain other blocks with recursive
369
parsing.
370
7. **Horizontal rule:** line with at least 3 characters, hyphens,
371
underscores, or asterisks, optionally with spaces.
372
Inline elements
374
---------------
375
### Text
377
Technically not an inline element, represented by a simple text in the
378
output. Anything not otherwise recognised is text.
379
### Emphasis
381
Emphasis is represented by `*` or `_` surrounding the text. When using `_`,
382
the emphasis must be surrounded by spaces or start/end of the line.
383
There can be at most 7 markers on each side, the number of opening markers
385
must be exactly the same as the number of closing markers,
386
and they cannot be mixed, unlike in standard markdown. (Maybe this will change
387
in the future, but we'll see.) However mixing them sometimes works, only when
388
nesting makes sense.
389
The number of markers is interpreted as a sum of powers of 2. If it's 4 or
391
more then there's the third level of emphasis, if the remainder is 2 or more
392
then there's the second level of emphasis, and if there's a remainder then
393
there's the first level of emphasis. You can see how they look below:
394
1. *level 1*
396
2. **level 2**
397
3. ***level 1+2***
398
4. ****level 3****
399
5. *****level 1+3*****
400
6. ******level 2+3******
401
7. *******level 1+2+3*******
402
The roundabout styles level 1 as italic, level 2 as bold, and level 3 as
404
underlined.
405
### Strikethrough
407
Strikethrough is represented by `~~` surrounding the text.
408
### Diff marker
410
Diff markers are represented by `++` on either side of the text for inserted
411
text and `--` for deleted text.
412
### Link
414
Links are represented by `[text](url)`. The text can contain inline elements.
415
Title attributes are currently not supported, but they will be.
416
#### Autolink
418
Autolinks are represented by `<url>`. With an autolink, the URL is the link
419
text as well.
420
#### Image
422
Images are represented by ``.
423
### Code
425
Code is represented by ``` surrounding the text.
426
Using two backticks is not currently supported.
427
### Summary of inline elements
429
1. **Text:** anything not recognised as another inline element.
430
2. **Emphasis:** `*` or `_` surrounding the text, at most 7 markers on each side.
431
3. **Strikethrough:** `~~` surrounding the text.
432
4. **Diff marker:** `++` or `--` surrounding the text.
433
5. **Link:** `[text](url)`, text can contain inline elements.
434
6. **Image:** ``.
435
7. **Code:** ``` surrounding the text.
436